
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Writing database migrations &#8212; Django 2.2.12.dev20200304094918 documentation</title>
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Django FAQ" href="../faq/index.html" />
    <link rel="prev" title="How to install Django on Windows" href="windows.html" />



 
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);</script>

  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../index.html">Django 2.2.12.dev20200304094918 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../index.html">Home</a>  |
        <a title="Table of contents" href="../contents.html">Table of contents</a>  |
        <a title="Global index" href="../genindex.html">Index</a>  |
        <a title="Module index" href="../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="windows.html" title="How to install Django on Windows">previous</a>
     |
    <a href="index.html" title="“How-to” guides" accesskey="U">up</a>
   |
    <a href="../faq/index.html" title="Django FAQ">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="howto-writing-migrations">
            
  <div class="section" id="s-writing-database-migrations">
<span id="writing-database-migrations"></span><h1>Writing database migrations<a class="headerlink" href="#writing-database-migrations" title="Permalink to this headline">¶</a></h1>
<p>This document explains how to structure and write database migrations for
different scenarios you might encounter. For introductory material on
migrations, see <a class="reference internal" href="../topics/migrations.html"><span class="doc">the topic guide</span></a>.</p>
<div class="section" id="s-data-migrations-and-multiple-databases">
<span id="s-id1"></span><span id="data-migrations-and-multiple-databases"></span><span id="id1"></span><h2>Data migrations and multiple databases<a class="headerlink" href="#data-migrations-and-multiple-databases" title="Permalink to this headline">¶</a></h2>
<p>When using multiple databases, you may need to figure out whether or not to
run a migration against a particular database. For example, you may want to
<strong>only</strong> run a migration on a particular database.</p>
<p>In order to do that you can check the database connection’s alias inside a
<code class="docutils literal notranslate"><span class="pre">RunPython</span></code> operation by looking at the <code class="docutils literal notranslate"><span class="pre">schema_editor.connection.alias</span></code>
attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">migrations</span>

<span class="k">def</span> <span class="nf">forwards</span><span class="p">(</span><span class="n">apps</span><span class="p">,</span> <span class="n">schema_editor</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">schema_editor</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">alias</span> <span class="o">!=</span> <span class="s1">&#39;default&#39;</span><span class="p">:</span>
        <span class="k">return</span>
    <span class="c1"># Your migration code goes here</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>

    <span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
        <span class="c1"># Dependencies to other migrations</span>
    <span class="p">]</span>

    <span class="n">operations</span> <span class="o">=</span> <span class="p">[</span>
        <span class="n">migrations</span><span class="o">.</span><span class="n">RunPython</span><span class="p">(</span><span class="n">forwards</span><span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
<p>You can also provide hints that will be passed to the <a class="reference internal" href="../topics/db/multi-db.html#allow_migrate" title="allow_migrate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">allow_migrate()</span></code></a>
method of database routers as <code class="docutils literal notranslate"><span class="pre">**hints</span></code>:</p>
<div class="literal-block-wrapper docutils container" id="id3">
<div class="code-block-caption"><span class="caption-text">myapp/dbrouters.py</span><a class="headerlink" href="#id3" title="Permalink to this code">¶</a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyRouter</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">allow_migrate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="p">,</span> <span class="n">app_label</span><span class="p">,</span> <span class="n">model_name</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="o">**</span><span class="n">hints</span><span class="p">):</span>
        <span class="k">if</span> <span class="s1">&#39;target_db&#39;</span> <span class="ow">in</span> <span class="n">hints</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">db</span> <span class="o">==</span> <span class="n">hints</span><span class="p">[</span><span class="s1">&#39;target_db&#39;</span><span class="p">]</span>
        <span class="k">return</span> <span class="bp">True</span>
</pre></div>
</div>
</div>
<p>Then, to leverage this in your migrations, do the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">migrations</span>

<span class="k">def</span> <span class="nf">forwards</span><span class="p">(</span><span class="n">apps</span><span class="p">,</span> <span class="n">schema_editor</span><span class="p">):</span>
    <span class="c1"># Your migration code goes here</span>
    <span class="o">...</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>

    <span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
        <span class="c1"># Dependencies to other migrations</span>
    <span class="p">]</span>

    <span class="n">operations</span> <span class="o">=</span> <span class="p">[</span>
        <span class="n">migrations</span><span class="o">.</span><span class="n">RunPython</span><span class="p">(</span><span class="n">forwards</span><span class="p">,</span> <span class="n">hints</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;target_db&#39;</span><span class="p">:</span> <span class="s1">&#39;default&#39;</span><span class="p">}),</span>
    <span class="p">]</span>
</pre></div>
</div>
<p>If your <code class="docutils literal notranslate"><span class="pre">RunPython</span></code> or <code class="docutils literal notranslate"><span class="pre">RunSQL</span></code> operation only affects one model, it’s good
practice to pass <code class="docutils literal notranslate"><span class="pre">model_name</span></code> as a hint to make it as transparent as possible
to the router. This is especially important for reusable and third-party apps.</p>
</div>
<div class="section" id="s-migrations-that-add-unique-fields">
<span id="migrations-that-add-unique-fields"></span><h2>Migrations that add unique fields<a class="headerlink" href="#migrations-that-add-unique-fields" title="Permalink to this headline">¶</a></h2>
<p>Applying a “plain” migration that adds a unique non-nullable field to a table
with existing rows will raise an error because the value used to populate
existing rows is generated only once, thus breaking the unique constraint.</p>
<p>Therefore, the following steps should be taken. In this example, we’ll add a
non-nullable <a class="reference internal" href="../ref/models/fields.html#django.db.models.UUIDField" title="django.db.models.UUIDField"><code class="xref py py-class docutils literal notranslate"><span class="pre">UUIDField</span></code></a> with a default value. Modify
the respective field according to your needs.</p>
<ul>
<li><p class="first">Add the field on your model with <code class="docutils literal notranslate"><span class="pre">default=uuid.uuid4</span></code> and <code class="docutils literal notranslate"><span class="pre">unique=True</span></code>
arguments (choose an appropriate default for the type of the field you’re
adding).</p>
</li>
<li><p class="first">Run the <a class="reference internal" href="../ref/django-admin.html#django-admin-makemigrations"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">makemigrations</span></code></a> command. This should generate a migration
with an <code class="docutils literal notranslate"><span class="pre">AddField</span></code> operation.</p>
</li>
<li><p class="first">Generate two empty migration files for the same app by running
<code class="docutils literal notranslate"><span class="pre">makemigrations</span> <span class="pre">myapp</span> <span class="pre">--empty</span></code> twice. We’ve renamed the migration files to
give them meaningful names in the examples below.</p>
</li>
<li><p class="first">Copy the <code class="docutils literal notranslate"><span class="pre">AddField</span></code> operation from the auto-generated migration (the first
of the three new files) to the last migration, change <code class="docutils literal notranslate"><span class="pre">AddField</span></code> to
<code class="docutils literal notranslate"><span class="pre">AlterField</span></code>, and add imports of <code class="docutils literal notranslate"><span class="pre">uuid</span></code> and <code class="docutils literal notranslate"><span class="pre">models</span></code>. For example:</p>
<div class="literal-block-wrapper docutils container" id="id4">
<div class="code-block-caption"><span class="caption-text">0006_remove_uuid_null.py</span><a class="headerlink" href="#id4" title="Permalink to this code">¶</a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Generated by Django A.B on YYYY-MM-DD HH:MM</span>
<span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">migrations</span><span class="p">,</span> <span class="n">models</span>
<span class="kn">import</span> <span class="nn">uuid</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>

    <span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
        <span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;0005_populate_uuid_values&#39;</span><span class="p">),</span>
    <span class="p">]</span>

    <span class="n">operations</span> <span class="o">=</span> <span class="p">[</span>
        <span class="n">migrations</span><span class="o">.</span><span class="n">AlterField</span><span class="p">(</span>
            <span class="n">model_name</span><span class="o">=</span><span class="s1">&#39;mymodel&#39;</span><span class="p">,</span>
            <span class="n">name</span><span class="o">=</span><span class="s1">&#39;uuid&#39;</span><span class="p">,</span>
            <span class="n">field</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">UUIDField</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">,</span> <span class="n">unique</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
        <span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
</div>
</li>
<li><p class="first">Edit the first migration file. The generated migration class should look
similar to this:</p>
<div class="literal-block-wrapper docutils container" id="id5">
<div class="code-block-caption"><span class="caption-text">0004_add_uuid_field.py</span><a class="headerlink" href="#id5" title="Permalink to this code">¶</a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>

    <span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
        <span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;0003_auto_20150129_1705&#39;</span><span class="p">),</span>
    <span class="p">]</span>

    <span class="n">operations</span> <span class="o">=</span> <span class="p">[</span>
        <span class="n">migrations</span><span class="o">.</span><span class="n">AddField</span><span class="p">(</span>
            <span class="n">model_name</span><span class="o">=</span><span class="s1">&#39;mymodel&#39;</span><span class="p">,</span>
            <span class="n">name</span><span class="o">=</span><span class="s1">&#39;uuid&#39;</span><span class="p">,</span>
            <span class="n">field</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">UUIDField</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">,</span> <span class="n">unique</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
        <span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
</div>
<p>Change <code class="docutils literal notranslate"><span class="pre">unique=True</span></code> to <code class="docutils literal notranslate"><span class="pre">null=True</span></code> – this will create the intermediary
null field and defer creating the unique constraint until we’ve populated
unique values on all the rows.</p>
</li>
<li><p class="first">In the first empty migration file, add a
<a class="reference internal" href="../ref/migration-operations.html#django.db.migrations.operations.RunPython" title="django.db.migrations.operations.RunPython"><code class="xref py py-class docutils literal notranslate"><span class="pre">RunPython</span></code></a> or
<a class="reference internal" href="../ref/migration-operations.html#django.db.migrations.operations.RunSQL" title="django.db.migrations.operations.RunSQL"><code class="xref py py-class docutils literal notranslate"><span class="pre">RunSQL</span></code></a> operation to generate a
unique value (UUID in the example) for each existing row. Also add an import
of <code class="docutils literal notranslate"><span class="pre">uuid</span></code>. For example:</p>
<div class="literal-block-wrapper docutils container" id="id6">
<div class="code-block-caption"><span class="caption-text">0005_populate_uuid_values.py</span><a class="headerlink" href="#id6" title="Permalink to this code">¶</a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Generated by Django A.B on YYYY-MM-DD HH:MM</span>
<span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">migrations</span>
<span class="kn">import</span> <span class="nn">uuid</span>

<span class="k">def</span> <span class="nf">gen_uuid</span><span class="p">(</span><span class="n">apps</span><span class="p">,</span> <span class="n">schema_editor</span><span class="p">):</span>
    <span class="n">MyModel</span> <span class="o">=</span> <span class="n">apps</span><span class="o">.</span><span class="n">get_model</span><span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;MyModel&#39;</span><span class="p">)</span>
    <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">MyModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">():</span>
        <span class="n">row</span><span class="o">.</span><span class="n">uuid</span> <span class="o">=</span> <span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">()</span>
        <span class="n">row</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">update_fields</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;uuid&#39;</span><span class="p">])</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>

    <span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
        <span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;0004_add_uuid_field&#39;</span><span class="p">),</span>
    <span class="p">]</span>

    <span class="n">operations</span> <span class="o">=</span> <span class="p">[</span>
        <span class="c1"># omit reverse_code=... if you don&#39;t want the migration to be reversible.</span>
        <span class="n">migrations</span><span class="o">.</span><span class="n">RunPython</span><span class="p">(</span><span class="n">gen_uuid</span><span class="p">,</span> <span class="n">reverse_code</span><span class="o">=</span><span class="n">migrations</span><span class="o">.</span><span class="n">RunPython</span><span class="o">.</span><span class="n">noop</span><span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
</div>
</li>
<li><p class="first">Now you can apply the migrations as usual with the <a class="reference internal" href="../ref/django-admin.html#django-admin-migrate"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">migrate</span></code></a> command.</p>
<p>Note there is a race condition if you allow objects to be created while this
migration is running. Objects created after the <code class="docutils literal notranslate"><span class="pre">AddField</span></code> and before
<code class="docutils literal notranslate"><span class="pre">RunPython</span></code> will have their original <code class="docutils literal notranslate"><span class="pre">uuid</span></code>’s overwritten.</p>
</li>
</ul>
<div class="section" id="s-non-atomic-migrations">
<span id="s-id2"></span><span id="non-atomic-migrations"></span><span id="id2"></span><h3>Non-atomic migrations<a class="headerlink" href="#non-atomic-migrations" title="Permalink to this headline">¶</a></h3>
<p>On databases that support DDL transactions (SQLite and PostgreSQL), migrations
will run inside a transaction by default. For use cases such as performing data
migrations on large tables, you may want to prevent a migration from running in
a transaction by setting the <code class="docutils literal notranslate"><span class="pre">atomic</span></code> attribute to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">migrations</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>
    <span class="n">atomic</span> <span class="o">=</span> <span class="kc">False</span>
</pre></div>
</div>
<p>Within such a migration, all operations are run without a transaction. It’s
possible to execute parts of the migration inside a transaction using
<a class="reference internal" href="../topics/db/transactions.html#django.db.transaction.atomic" title="django.db.transaction.atomic"><code class="xref py py-func docutils literal notranslate"><span class="pre">atomic()</span></code></a> or by passing <code class="docutils literal notranslate"><span class="pre">atomic=True</span></code> to
<code class="docutils literal notranslate"><span class="pre">RunPython</span></code>.</p>
<p>Here’s an example of a non-atomic data migration that updates a large table in
smaller batches:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">uuid</span>

<span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">migrations</span><span class="p">,</span> <span class="n">transaction</span>

<span class="k">def</span> <span class="nf">gen_uuid</span><span class="p">(</span><span class="n">apps</span><span class="p">,</span> <span class="n">schema_editor</span><span class="p">):</span>
    <span class="n">MyModel</span> <span class="o">=</span> <span class="n">apps</span><span class="o">.</span><span class="n">get_model</span><span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;MyModel&#39;</span><span class="p">)</span>
    <span class="k">while</span> <span class="n">MyModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">uuid__isnull</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
        <span class="k">with</span> <span class="n">transaction</span><span class="o">.</span><span class="n">atomic</span><span class="p">():</span>
            <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">MyModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">uuid__isnull</span><span class="o">=</span><span class="kc">True</span><span class="p">)[:</span><span class="mi">1000</span><span class="p">]:</span>
                <span class="n">row</span><span class="o">.</span><span class="n">uuid</span> <span class="o">=</span> <span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">()</span>
                <span class="n">row</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>
    <span class="n">atomic</span> <span class="o">=</span> <span class="kc">False</span>

    <span class="n">operations</span> <span class="o">=</span> <span class="p">[</span>
        <span class="n">migrations</span><span class="o">.</span><span class="n">RunPython</span><span class="p">(</span><span class="n">gen_uuid</span><span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">atomic</span></code> attribute doesn’t have an effect on databases that don’t support
DDL transactions (e.g. MySQL, Oracle). (MySQL’s <a class="reference external" href="https://dev.mysql.com/doc/refman/en/atomic-ddl.html">atomic DDL statement support</a> refers to individual
statements rather than multiple statements wrapped in a transaction that can be
rolled back.)</p>
</div>
</div>
<div class="section" id="s-controlling-the-order-of-migrations">
<span id="controlling-the-order-of-migrations"></span><h2>Controlling the order of migrations<a class="headerlink" href="#controlling-the-order-of-migrations" title="Permalink to this headline">¶</a></h2>
<p>Django determines the order in which migrations should be applied not by the
filename of each migration, but by building a graph using two properties on the
<code class="docutils literal notranslate"><span class="pre">Migration</span></code> class: <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> and <code class="docutils literal notranslate"><span class="pre">run_before</span></code>.</p>
<p>If you’ve used the <a class="reference internal" href="../ref/django-admin.html#django-admin-makemigrations"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">makemigrations</span></code></a> command you’ve probably
already seen <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> in action because auto-created
migrations have this defined as part of their creation process.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> property is declared like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">migrations</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>

    <span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
        <span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;0123_the_previous_migration&#39;</span><span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
<p>Usually this will be enough, but from time to time you may need to
ensure that your migration runs <em>before</em> other migrations. This is
useful, for example, to make third-party apps’ migrations run <em>after</em>
your <a class="reference internal" href="../ref/settings.html#std:setting-AUTH_USER_MODEL"><code class="xref std std-setting docutils literal notranslate"><span class="pre">AUTH_USER_MODEL</span></code></a> replacement.</p>
<p>To achieve this, place all migrations that should depend on yours in
the <code class="docutils literal notranslate"><span class="pre">run_before</span></code> attribute on your <code class="docutils literal notranslate"><span class="pre">Migration</span></code> class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>
    <span class="o">...</span>

    <span class="n">run_before</span> <span class="o">=</span> <span class="p">[</span>
        <span class="p">(</span><span class="s1">&#39;third_party_app&#39;</span><span class="p">,</span> <span class="s1">&#39;0001_do_awesome&#39;</span><span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
<p>Prefer using <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> over <code class="docutils literal notranslate"><span class="pre">run_before</span></code> when possible. You should
only use <code class="docutils literal notranslate"><span class="pre">run_before</span></code> if it is undesirable or impractical to specify
<code class="docutils literal notranslate"><span class="pre">dependencies</span></code> in the migration which you want to run after the one you are
writing.</p>
</div>
<div class="section" id="s-migrating-data-between-third-party-apps">
<span id="migrating-data-between-third-party-apps"></span><h2>Migrating data between third-party apps<a class="headerlink" href="#migrating-data-between-third-party-apps" title="Permalink to this headline">¶</a></h2>
<p>You can use a data migration to move data from one third-party application to
another.</p>
<p>If you plan to remove the old app later, you’ll need to set the <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>
property based on whether or not the old app is installed. Otherwise, you’ll
have missing dependencies once you uninstall the old app. Similarly, you’ll
need to catch <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#LookupError" title="(in Python v3.8)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a> in the <code class="docutils literal notranslate"><span class="pre">apps.get_model()</span></code> call that
retrieves models from the old app. This approach allows you to deploy your
project anywhere without first installing and then uninstalling the old app.</p>
<p>Here’s a sample migration:</p>
<div class="literal-block-wrapper docutils container" id="id7">
<div class="code-block-caption"><span class="caption-text">myapp/migrations/0124_move_old_app_to_new_app.py</span><a class="headerlink" href="#id7" title="Permalink to this code">¶</a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.apps</span> <span class="kn">import</span> <span class="n">apps</span> <span class="k">as</span> <span class="n">global_apps</span>
<span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">migrations</span>

<span class="k">def</span> <span class="nf">forwards</span><span class="p">(</span><span class="n">apps</span><span class="p">,</span> <span class="n">schema_editor</span><span class="p">):</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">OldModel</span> <span class="o">=</span> <span class="n">apps</span><span class="o">.</span><span class="n">get_model</span><span class="p">(</span><span class="s1">&#39;old_app&#39;</span><span class="p">,</span> <span class="s1">&#39;OldModel&#39;</span><span class="p">)</span>
    <span class="k">except</span> <span class="ne">LookupError</span><span class="p">:</span>
        <span class="c1"># The old app isn&#39;t installed.</span>
        <span class="k">return</span>

    <span class="n">NewModel</span> <span class="o">=</span> <span class="n">apps</span><span class="o">.</span><span class="n">get_model</span><span class="p">(</span><span class="s1">&#39;new_app&#39;</span><span class="p">,</span> <span class="s1">&#39;NewModel&#39;</span><span class="p">)</span>
    <span class="n">NewModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">bulk_create</span><span class="p">(</span>
        <span class="n">NewModel</span><span class="p">(</span><span class="n">new_attribute</span><span class="o">=</span><span class="n">old_object</span><span class="o">.</span><span class="n">old_attribute</span><span class="p">)</span>
        <span class="k">for</span> <span class="n">old_object</span> <span class="ow">in</span> <span class="n">OldModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
    <span class="p">)</span>

<span class="k">class</span> <span class="nc">Migration</span><span class="p">(</span><span class="n">migrations</span><span class="o">.</span><span class="n">Migration</span><span class="p">):</span>
    <span class="n">operations</span> <span class="o">=</span> <span class="p">[</span>
        <span class="n">migrations</span><span class="o">.</span><span class="n">RunPython</span><span class="p">(</span><span class="n">forwards</span><span class="p">,</span> <span class="n">migrations</span><span class="o">.</span><span class="n">RunPython</span><span class="o">.</span><span class="n">noop</span><span class="p">),</span>
    <span class="p">]</span>
    <span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
        <span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;0123_the_previous_migration&#39;</span><span class="p">),</span>
        <span class="p">(</span><span class="s1">&#39;new_app&#39;</span><span class="p">,</span> <span class="s1">&#39;0001_initial&#39;</span><span class="p">),</span>
    <span class="p">]</span>

    <span class="k">if</span> <span class="n">global_apps</span><span class="o">.</span><span class="n">is_installed</span><span class="p">(</span><span class="s1">&#39;old_app&#39;</span><span class="p">):</span>
        <span class="n">dependencies</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="s1">&#39;old_app&#39;</span><span class="p">,</span> <span class="s1">&#39;0001_initial&#39;</span><span class="p">))</span>
</pre></div>
</div>
</div>
<p>Also consider what you want to happen when the migration is unapplied. You
could either do nothing (as in the example above) or remove some or all of the
data from the new application. Adjust the second argument of the
<a class="reference internal" href="../ref/migration-operations.html#django.db.migrations.operations.RunPython" title="django.db.migrations.operations.RunPython"><code class="xref py py-mod docutils literal notranslate"><span class="pre">RunPython</span></code></a> operation accordingly.</p>
</div>
<div class="section" id="s-changing-an-unmanaged-model-to-managed">
<span id="changing-an-unmanaged-model-to-managed"></span><h2>Changing an unmanaged model to managed<a class="headerlink" href="#changing-an-unmanaged-model-to-managed" title="Permalink to this headline">¶</a></h2>
<p>If you want to change an unmanaged model (<a class="reference internal" href="../ref/models/options.html#django.db.models.Options.managed" title="django.db.models.Options.managed"><code class="xref py py-attr docutils literal notranslate"><span class="pre">managed=False</span></code></a>) to managed, you must remove
<code class="docutils literal notranslate"><span class="pre">managed=False</span></code> and generate a migration before making other schema-related
changes to the model, since schema changes that appear in the migration that
contains the operation to change <code class="docutils literal notranslate"><span class="pre">Meta.managed</span></code> may not be applied.</p>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Writing database migrations</a><ul>
<li><a class="reference internal" href="#data-migrations-and-multiple-databases">Data migrations and multiple databases</a></li>
<li><a class="reference internal" href="#migrations-that-add-unique-fields">Migrations that add unique fields</a><ul>
<li><a class="reference internal" href="#non-atomic-migrations">Non-atomic migrations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#controlling-the-order-of-migrations">Controlling the order of migrations</a></li>
<li><a class="reference internal" href="#migrating-data-between-third-party-apps">Migrating data between third-party apps</a></li>
<li><a class="reference internal" href="#changing-an-unmanaged-model-to-managed">Changing an unmanaged model to managed</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="windows.html"
                        title="previous chapter">How to install Django on Windows</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="../faq/index.html"
                        title="next chapter">Django FAQ</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/howto/writing-migrations.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Mar 04, 2020</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="windows.html" title="How to install Django on Windows">previous</a>
     |
    <a href="index.html" title="“How-to” guides" accesskey="U">up</a>
   |
    <a href="../faq/index.html" title="Django FAQ">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>